org.sadun.text.ffp
Class FlatFileParser

java.lang.Object
  org.sadun.text.ffp.FlatFileParser

Direct Known Subclasses:

ManagedFlatFileParser

public class FlatFileParser

extends java.lang.Object

A parser for flat files.

This parser employs LineFormat objects to specify the format of the flat file. The FlatFileParser(LineFormat) constructor is useful when the flat file is simple, each logical line having identical format. Together with LineFormat.fromImage(String) allows to declare the parser and the format in one line of code:

  FlatFileParser ffp = new FlatFileParser(LineFormat.fromImage("##### type1 @@@ @@@"));
 

will parse flat files with a number in position 0-5, the constant type1 at position 5-10, and two alphanumeric fields of three characters each (see LineFormat for image syntax).

Alternatively, if a flat file contains lines with different formats, the corresponding LineFormat objects can be associated to a condition by using #declare(Condition, LineFormat).

Parsing will occur by registering a FlatFileParser.Listener (or associating a specific listener to each line format by using addDispatch and invoking one of the parse() methods:

  ffp.addListener(new EchoListener());
  ffp.parse(new File("myfile.txt"));
 

For each line, the parser will examine the conditions and use the line format which matches. Only one condition is allowed to match for each line, and it's programmer responsability to ensure that the given conditions do not overlap.

Version:

2.0

Author:

Cristiano Sadun

Nested Class Summary

static interface	FlatFileParser.AdvancedListener Classes implementing this extension of Listener will receive more events on flat file parsing.
static interface	FlatFileParser.Condition An object implementing this interface can decide whether or not the physical line currently available for reading match or not a certain condition, in the FlatFileParser.Condition#holds(int, int, LineReader) method.
static interface	FlatFileParser.LineReader Objects implementing this interface allow to access the flat file during parsing, from outside the parser.
static interface	FlatFileParser.Listener Classes implementing this interface can be registered in a FlatFileParser (using FlatFileParser#addListener(Listener)) to react to successfully parsed lines in the flat file.
static interface	FlatFileParser.UnmatchedLineListener Classes implementing this extension of Listener will receive notification about lines where no condition matches on parsing, if the failOnNoMatchingConditions property is false.

Field Summary

static boolean	defaultFailOnLineParsingError The default value used to intialize the failOnLineParsingError property when a parser instance is constructed.
static java.lang.String	LOGGER_CHANNEL_NAME The logger channel used by this package.

Constructor Summary

FlatFileParser()
Create a parser with no associated line formats.

FlatFileParser(LineFormat format)
Creates a parser which parses flat files whose all lines have the given format.

Method Summary

void	addDispatch(LineFormat format, FlatFileParser.Listener l) Associates the given LineFormat to the given listener, so that when a line is parsed by the given format, the event is sent to the given listener.
void	addListener(FlatFileParser.Listener l) Add the given listener to the registered listeners set.
void	declare(FlatFileParser.Condition condition, LineFormat format) Declare that a certain LineFormat is to be used under the given condition.
void	declare(FlatFileParser.Condition condition, java.lang.String formatImage) Declare that a certain LineFormat, whose image is given, is to be used under the given condition.
void	declare(LineFormat format) Declare that the only line format recognized by the parser be the one given.
void	declare(java.lang.String formatImage) Declare that the only line format recognized by the parser be the one whose image is given.
protected java.util.Map	getFieldsByCondition()
java.lang.String	getLineSeparator() Return the line separator string used by this parser.
boolean	isAutoTrimMode() Return the current state of the auto trim mode.
boolean	isFailOnLineParsingError() Return whether or not the parser should fail when a exception occurs parsing a line, or just emit a warning on the LOGGER_CHANNEL_NAME channel.
boolean	isFailOnNoMatchingConditions() Return whether the parser will fail or not if no conditions match a line.
boolean	isFastMatchMode() Return the current state of the the fast match mode.
void	parse(java.io.File file) Parse the text from in the given file.
void	parse(java.io.Reader sourceReader) Parse the text from the given reader.
void	removeListener(FlatFileParser.Listener l) Remove the given listener from the registered listeners set.
void	setAutoTrimMode(boolean autoTrimMode) Set the auto trim mode.
void	setFailOnLineParsingError(boolean failOnLineParsingError) Set whether or not the parser should fail when a exception occurs parsing a line, or just emit a warning on the LOGGER_CHANNEL_NAME channel.
void	setFailOnNoMatchingConditions(boolean failOnNoMatchingConditions) Set whether the parser will fail or not if no conditions match a line.
void	setFastMatchMode(boolean fastMatchMode) Set the current state of the the fast match mode.
void	setLineSeparator(java.lang.String lineSeparator) Set the line separator string used by this parser.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOGGER_CHANNEL_NAME

public static final java.lang.String LOGGER_CHANNEL_NAME

The logger channel used by this package. Its value is org.sadun.text.ffp.

See Also:

Constant Field Values

defaultFailOnLineParsingError

public static boolean defaultFailOnLineParsingError

The default value used to intialize the failOnLineParsingError property when a parser instance is constructed.

Constructor Detail

FlatFileParser

public FlatFileParser()

Create a parser with no associated line formats.

Before running parse(Reader), at least one format must be added by invoking declare().

FlatFileParser

public FlatFileParser(LineFormat format)

Creates a parser which parses flat files whose all lines have the given format.

Parameters:

format -

Method Detail

declare

public void declare(FlatFileParser.Condition condition,
                    LineFormat format)

Declare that a certain LineFormat is to be used under the given condition.

Parameters:

condition - the FlatFileParser.Condition condition that must hold.

format - the LineFormat to use.

declare

public void declare(LineFormat format)

Declare that the only line format recognized by the parser be the one given. Further declarations (i.e. further invocations of any declare() overload) will fail.

Invoking this method after creating a parser with new FlatFileParser() is equivalent to use the constructor FlatFileParser(LineFormat).

Parameters:

format - the LineFormat to use for each line in the flat file.

declare

public void declare(java.lang.String formatImage)
             throws ImageParseException

Declare that the only line format recognized by the parser be the one whose image is given. Further declarations (i.e. further invocations of any declare() overload) will fail.

Invoking this method after creating a parser with new FlatFileParser() is equivalent to use the constructor FlatFileParser(LineFormat).

Parameters:

formatImage - the LineFormat's image to use for each line in the flat file.

Throws:

ImageParseException - if the given image is not correct

See Also:

{@link LineFormat#fromImage(String)}

declare

public void declare(FlatFileParser.Condition condition,
                    java.lang.String formatImage)
             throws ImageParseException

Declare that a certain LineFormat, whose image is given, is to be used under the given condition.

Parameters:

condition - the FlatFileParser.Condition condition that must hold.

formatImage - the LineFormat's image to use for each line in the flat file.

Throws:

ImageParseException - if the given image is not correct

See Also:

{@link LineFormat#fromImage(String)}

parse

public void parse(java.io.File file)
           throws java.io.IOException,
                  FFPParseException

Parse the text from in the given file.

Notification of successful parsed lines is sent to any registered FlatFileParser.Listener (FlatFileParser#addListener(Listener) is used for registration).

Parameters:

file - the file to parse

Throws:

java.io.IOException - if an I/O exception occurs

FFPParseException - if the text format cannot be parsed correctly

parse

public void parse(java.io.Reader sourceReader)
           throws java.io.IOException,
                  FFPParseException

Parse the text from the given reader.

Notification of successful parsed lines is sent to any registered FlatFileParser.Listener (FlatFileParser#addListener(Listener) is used for registration).

Parameters:

sourceReader - the reader to read the text from

Throws:

java.io.IOException - if an I/O exception occurs

FFPParseException - if the text format cannot be parsed correctly

addListener

public void addListener(FlatFileParser.Listener l)

Add the given listener to the registered listeners set.

See also #addDispatch(LineFormat, Listener).

Parameters:

l - the listener to add

addDispatch

public void addDispatch(LineFormat format,
                        FlatFileParser.Listener l)

Associates the given LineFormat to the given listener, so that when a line is parsed by the given format, the event is sent to the given listener.

An internal object of DispatcherListener class is used.

Parameters:

format - the line format on which the dispatch is to be based

l - the listener to associate

removeListener

public void removeListener(FlatFileParser.Listener l)

Remove the given listener from the registered listeners set.

Parameters:

l - the listener to remove

getLineSeparator

public java.lang.String getLineSeparator()

Return the line separator string used by this parser.

Returns:

the line separator string used by this parser.

setLineSeparator

public void setLineSeparator(java.lang.String lineSeparator)

Set the line separator string used by this parser. The separator is also set on all the LineFormats currently defined.

Parameters:

lineSeparator - the line separator string used by this parser.

isFailOnLineParsingError

public boolean isFailOnLineParsingError()

Return whether or not the parser should fail when a exception occurs parsing a line, or just emit a warning on the LOGGER_CHANNEL_NAME channel.

Returns:

whether or not the parser should fail when a exception occurs parsing a line, or just emit a warning on the LOGGER_CHANNEL_NAME channel.

setFailOnLineParsingError

public void setFailOnLineParsingError(boolean failOnLineParsingError)

Set whether or not the parser should fail when a exception occurs parsing a line, or just emit a warning on the LOGGER_CHANNEL_NAME channel.

Parameters:

failOnLineParsingError - if true, the parse(Reader) methods will fail if there's a parsing problem on a line.

isFastMatchMode

public boolean isFastMatchMode()

Return the current state of the the fast match mode. Fast match mode speeds up mixed line parsing by using the LineFormat associated of the last holding FlatFileParser.Condition if it still holds, avoiding to check all the conditions.

Returns:

the current state of the the fast match mode.

setFastMatchMode

public void setFastMatchMode(boolean fastMatchMode)

Set the current state of the the fast match mode. Fast match mode speeds up mixed line parsing by using the LineFormat associated of the last holding FlatFileParser.Condition if it still holds, avoiding to check all the conditions.

Parameters:

fastMatchMode - if true, enables the fastmatch mode, else disables it.

isAutoTrimMode

public boolean isAutoTrimMode()

Return the current state of the auto trim mode. In auto trim mode, strings are trimmed of trailing spaces before being notified to the listeners.

Returns:

the current state of the the auto trim mode.

setAutoTrimMode

public void setAutoTrimMode(boolean autoTrimMode)

Set the auto trim mode. In auto trim mode, strings are trimmed of trailing spaces before being notified to the listeners.

Parameters:

autoTrimMode - if true, enables the auto trim mode, else disables it.

getFieldsByCondition

protected java.util.Map getFieldsByCondition()

isFailOnNoMatchingConditions

public boolean isFailOnNoMatchingConditions()

Return whether the parser will fail or not if no conditions match a line.

Returns:

true if the parser will fail or not if no conditions match a line, otherwise false.

setFailOnNoMatchingConditions

public void setFailOnNoMatchingConditions(boolean failOnNoMatchingConditions)

Set whether the parser will fail or not if no conditions match a line.

Parameters:

failOnNoMatchingConditions - true if the parser must fail if no conditions match a line, otherwise false.